<html>
<head>
<title>Writing for the HTML Help System</title>
<body>
<h1>Writing for the HTML Help System</h1>
Contributions are very welcome. If you wish to make a contribution
to the HTML Help System, please contact the maintainer:
<pre>
   <a href="mailto:worldwiderob@yahoo.co.uk">worldwiderob@yahoo.co.uk</a>
</pre>
<h2>The structure of the \help directory</h2>
<pre>
<b>\help\index.htm</b>
  Lists the help languages installed on the system.
  Loaded automatically if LANG is not set to an available language
  and English (EN) not installed.

<b>\help\%LANG%\index.htm</b>
  HELP will load this by default.
  %LANG% is the language selected by setting the LANG environment
  variable. If LANG isn't set, EN is assumed.

<b>\help\%LANG%\help.htm</b>
  HELP will load this when the user presses F1 or clicks
  on "Help on Help".

<b>\help\docinfo\bi\nls\%LANG%.bi</b>
  Stores bookshelf files, for use with Aitor's bookshlf tool, to
  create the language index (\help\index.htm)
</pre>
<h2>Creating compressed help files</h2>
You should use for your compressed file set a name such as:
<pre>
  <b>\help\...\[name]\[name].zip</b>
  If you wish to compress your help files, they should be in the
  zip format. They should have the same filename as the directory
  they are stored in, and the zip extension. For instance:

        \help\en\myhelp\myhelp.zip

  The index.htm can be inside the zip file, but help and bookshlf
  will both work better if it is not.

  Directory structures are allowed within the zip file. However,
  encryption and some of the older and more obscure compression
  methods are not supported.
</pre>
<h2>Creating modified versions of the help files</h2>
<p>Use a distinct title on the title page (often index.htm)
in any modified versions. This is to avoid any confusion or conflicts,
and most importantly, is necessary under the
<a href="fdl.txt">GNU Free Documentation License</a> part 4A.
In addition to changing the title, please update the history,
list of authors etc, in accordance with section 4 of the 
<a href="fdl.txt">GNU Free Documentation License</a>.
<p>If the file set is meant to describe a new or modified package,
or if the file set undergoes a fundamental change (e.g. a translation),
then it is best to use a distinct subdirectory name, as expained in
"The structure of the \help directory" above.
This is simply a matter of doing a find and replace on the subdirectory
name in index.htm, and is well worth it.
<p>For example, a streamlined version of the "hhstndrd" file set might be called
"hhmicro". This would be the name of the subdirectory, and the title in index.htm
might be:
<pre>
   FreeDOS Help (hhmicro 1.0)
</pre>
<p>It is reasonable to change only the version number (rather than the
name and directory "hhmicro") when releasing updates.

<h2>Creating or adding new files</h2>
<p>It is advised that the following license message be put at the end of any
new help files
(unless it is going to be a stand alone file, not included in a help file set):</p>
<pre>
   ...
   &lt;hr&gt;
   &lt;address&gt;
   &lt;b&gt;Copyright &amp;copy; 2003
   &lt;a href="mailto:<b>myemail@address.com</b>"&gt;<b>My Name</b>&lt;/a&gt;&lt;/b&gt;&lt;br&gt;
   This file forms part of The FreeDOS HTML Help Documentation, and is
   covered under its terms, see
   &lt;a href="../index.htm"&gt;index.htm&lt;/a&gt;
   &lt;/address&gt;
   &lt;/body&gt;
   &lt;/html&gt;
</pre>
<p>Providing an email is entirely optional; if you load your help files onto a website, then
email addresses can be subjected to spamming.<br>
The terms are the <a href="fdl.txt">GNU Free Documentation License</a>.

<h2>Editing file stored in a zip</h2>
You may wish to unzip the html files so that they
can be read with another browser, or to edit them.
Zip files usually take priority over uncompressed files;
if you want to make sure that help reads an edited,
uncompressed version of a file, you should replace or
delete the original version inside that zip.

<h2>Testing help files</h2>
The reference browsers for testing help files are:
<ul>
<li>the FreeDOS HTML Help Viewer (help.exe)
<li>Netscape Navigator.
</ul>

<h2>Creating tables</h2>
Unfortunately, help does not support table tags. Use
the preformatting tags &lt;pre&gt; &lt;/pre&gt; for tables of
information.

<h2>General tips</h2>
<p>Press F5 or Ctrl+R to refresh the file being
displayed by Help. The effects of
changes to the file can be seen immediately. Useful when editing help
files in a windows-type environment.
<p>To use HTML Help Viewer to view files that aren't yet
integrated into the file set, the help path override
switch can be used:
<pre>
    help /O[drive:][path]filename[.htm]
</pre>
or if relative to the /HELP folder:
<pre>
    help /L[subdirs]filename[.htm]
</pre>
<h2>See also</h2>
<a href="tags.htm">Tags supported by HTML Help</a><br>
Back to <a href="index.htm">Authoring Resources</a>
<hr>
<address>
<b>Copyright &copy; 2003-4 <a href="mailto:worldwiderob@yahoo.co.uk">Robert Platt</a></b>
<br>This file forms part of The FreeDOS HTML Help Documentation, and is
covered under its terms: see <a href="../../index.htm#copying">index.htm</a>
</address>
</body>
</html>
